home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Object.java < prev    next >
Text File  |  1998-09-22  |  14KB  |  328 lines
  1. /*
  2.  * @(#)Object.java    1.40 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. /**
  18.  * Class <code>Object</code> is the root of the class hierarchy. 
  19.  * Every class has <code>Object</code> as a superclass. All objects, 
  20.  * including arrays, implement the methods of this class. 
  21.  *
  22.  * @author  unascribed
  23.  * @version 1.40, 07/01/98
  24.  * @see     java.lang.Class
  25.  * @since   JDK1.0
  26.  */
  27. public class Object {
  28.     /**
  29.      * Returns the runtime class of an object. 
  30.      *
  31.      * @return  the object of type <code>Class</code> that represents the
  32.      *          runtime class of the object.
  33.      * @since   JDK1.0
  34.      */
  35.     public final native Class getClass();
  36.  
  37.     /**
  38.      * Returns a hash code value for the object. This method is 
  39.      * supported for the benefit of hashtables such as those provided by 
  40.      * <code>java.util.Hashtable</code>. 
  41.      * <p>
  42.      * The general contract of <code>hashCode</code> is: 
  43.      * <ul>
  44.      * <li>Whenever it is invoked on the same object more than once during 
  45.      *     an execution of a Java application, the <code>hashCode</code> method 
  46.      *     must consistently return the same integer. This integer need not 
  47.      *     remain consistent from one execution of an application to another 
  48.      *     execution of the same application. 
  49.      * <li>If two objects are equal according to the <code>equals</code> 
  50.      *     method, then calling the <code>hashCode</code> method on each of the 
  51.      *     two objects must produce the same integer result. 
  52.      * </ul>
  53.      *
  54.      * @return  a hash code value for this object.
  55.      * @see     java.lang.Object#equals(java.lang.Object)
  56.      * @see     java.util.Hashtable
  57.      * @since   JDK1.0
  58.      */
  59.     public native int hashCode();
  60.  
  61.     /**
  62.      * Compares two Objects for equality.
  63.      * <p>
  64.      * The <code>equals</code> method implements an equivalence relation: 
  65.      * <ul>
  66.      * <li>It is <i>reflexive</i>: for any reference value <code>x</code>, 
  67.      *     <code>x.equals(x)</code> should return <code>true</code>. 
  68.      * <li>It is <i>symmetric</i>: for any reference values <code>x</code> and 
  69.      *     <code>y</code>, <code>x.equals(y)</code> should return 
  70.      *     <code>true</code> if and only if <code>y.equals(x)</code> returns 
  71.      *     <code>true</code>. 
  72.      * <li>It is <i>transitive</i>: for any reference values <code>x</code>, 
  73.      *     <code>y</code>, and <code>z</code>, if <code>x.equals(y)</code>
  74.      *     returns  <code>true</code> and <code>y.equals(z)</code> returns 
  75.      *     <code>true</code>, then <code>x.equals(z)</code> should return 
  76.      *     <code>true</code>. 
  77.      * <li>It is <i>consistent</i>: for any reference values <code>x</code> 
  78.      *     and <code>y</code>, multiple invocations of <code>x.equals(y)</code> 
  79.      *     consistently return <code>true</code> or consistently return 
  80.      *     <code>false</code>. 
  81.      * <li>For any reference value <code>x</code>, <code>x.equals(null)</code> 
  82.      *     should return <code>false</code>.
  83.      * </ul>
  84.      * <p>
  85.      * The equals method for class <code>Object</code> implements the most 
  86.      * discriminating possible equivalence relation on objects; that is, 
  87.      * for any reference values <code>x</code> and <code>y</code>, this 
  88.      * method returns <code>true</code> if and only if <code>x</code> and 
  89.      * <code>y</code> refer to the same object (<code>x==y</code> has the 
  90.      * value <code>true</code>). 
  91.      *
  92.      * @param   obj   the reference object with which to compare.
  93.      * @return  <code>true</code> if this object is the same as the obj
  94.      *          argument; <code>false</code> otherwise.
  95.      * @see     java.lang.Boolean#hashCode()
  96.      * @see     java.util.Hashtable
  97.      * @since   JDK1.0
  98.      */
  99.     public boolean equals(Object obj) {
  100.     return (this == obj);
  101.     }
  102.  
  103.     /**
  104.      * Creates a new object of the same class as this object. It then 
  105.      * initializes each of the new object's fields by assigning it the 
  106.      * same value as the corresponding field in this object. No 
  107.      * constructor is called. 
  108.      * <p>
  109.      * The <code>clone</code> method of class <code>Object</code> will 
  110.      * only clone an object whose class indicates that it is willing for 
  111.      * its instances to be cloned. A class indicates that its instances 
  112.      * can be cloned by declaring that it implements the 
  113.      * <code>Cloneable</code> interface. 
  114.      *
  115.      * @return     a clone of this instance.
  116.      * @exception  CloneNotSupportedException  if the object's class does not
  117.      *               support the <code>Cloneable</code> interface. Subclasses
  118.      *               that override the <code>clone</code> method can also
  119.      *               throw this exception to indicate that an instance cannot
  120.      *               be cloned.
  121.      * @exception  OutOfMemoryError            if there is not enough memory.
  122.      * @see        java.lang.Cloneable
  123.      * @since      JDK1.0
  124.      */
  125.     protected native Object clone() throws CloneNotSupportedException;
  126.  
  127.     /**
  128.      * Returns a string representation of the object. In general, the 
  129.      * <code>toString</code> method returns a string that 
  130.      * "textually represents" this object. The result should 
  131.      * be a concise but informative representation that is easy for a 
  132.      * person to read.
  133.      * It is recommendedthat all subclasses override this method.
  134.      * <p>
  135.      * The <code>toString</code> method for class <code>Object</code> 
  136.      * returns a string consisting of the name of the class of which the 
  137.      * object is an instance, the at-sign character `<code>@</code>', and 
  138.      * the unsigned hexadecimal representation of the hash code of the 
  139.      * object. 
  140.      *
  141.      * @return  a string representation of the object.
  142.      * @since   JDK1.0
  143.      */
  144.     public String toString() {
  145.     return getClass().getName() + "@" + Integer.toHexString(hashCode());
  146.     }
  147.  
  148.     /**
  149.      * Wakes up a single thread that is waiting on this object's 
  150.      * monitor. A thread waits on an object's monitor by calling one of 
  151.      * the <code>wait</code> methods.
  152.      * <p>
  153.      * This method should only be called by a thread that is the owner 
  154.      * of this object's monitor. A thread becomes the owner of the 
  155.      * object's monitor in one of three ways: 
  156.      * <ul>
  157.      * <li>By executing a synchronized instance method of that object. 
  158.      * <li>By executing the body of a <code>synchronized</code> statement 
  159.      *     that synchronizes on the object. 
  160.      * <li>For objects of type <code>Class,</code> by executing a 
  161.      *     synchronized static method of that class. 
  162.      * </ul>
  163.      * <p>
  164.      * Only one thread at a time can own an object's monitor. 
  165.      *
  166.      * @exception  IllegalMonitorStateException  if the current thread is not
  167.      *               the owner of this object's monitor.
  168.      * @see        java.lang.Object#notifyAll()
  169.      * @see        java.lang.Object#wait()
  170.      * @since      JDK1.0
  171.      */
  172.     public final native void notify();
  173.  
  174.     /**
  175.      * Wakes up all threads that are waiting on this object's monitor. A 
  176.      * thread waits on an object's monitor by calling one of the 
  177.      * <code>wait</code> methods.
  178.      * <p>
  179.      * This method should only be called by a thread that is the owner 
  180.      * of this object's monitor. See the <code>notify</code> method for a 
  181.      * description of the ways in which a thread can become the owner of 
  182.      * a monitor. 
  183.      *
  184.      * @exception  IllegalMonitorStateException  if the current thread is not
  185.      *               the owner of this object's monitor.
  186.      * @see        java.lang.Object#notify()
  187.      * @see        java.lang.Object#wait()
  188.      * @since      JDK1.0
  189.      */
  190.     public final native void notifyAll();
  191.  
  192.     /**
  193.      * Waits to be notified by another thread of a change in this object.
  194.      * <p>
  195.      * The current thread must own this object's monitor. The thread 
  196.      * releases ownership of this monitor and waits until either of the 
  197.      * following two conditions has occurred: 
  198.      * <ul>
  199.      * <li>Another thread notifies threads waiting on this object's monitor 
  200.      *     to wake up either through a call to the <code>notify</code> method 
  201.      *     or the <code>notifyAll</code> method. 
  202.      * <li>The timeout period, specified by the <code>timeout</code> 
  203.      *     argument in milliseconds, has elapsed. 
  204.      * </ul>
  205.      * <p>
  206.      * The thread then waits until it can re-obtain ownership of the 
  207.      * monitor and resumes execution. 
  208.      * <p>
  209.      * This method should only be called by a thread that is the owner 
  210.      * of this object's monitor. See the <code>notify</code> method for a 
  211.      * description of the ways in which a thread can become the owner of 
  212.      * a monitor. 
  213.      *
  214.      * @param      timeout   the maximum time to wait in milliseconds.
  215.      * @exception  IllegalArgumentException      if the value of timeout is
  216.      *             negative.
  217.      * @exception  IllegalMonitorStateException  if the current thread is not
  218.      *               the owner of the object's monitor.
  219.      * @exception  InterruptedException          if another thread has
  220.      *               interrupted this thread.
  221.      * @see        java.lang.Object#notify()
  222.      * @see        java.lang.Object#notifyAll()
  223.      * @since      JDK1.0
  224.      */
  225.     public final native void wait(long timeout) throws InterruptedException;
  226.  
  227.     /**
  228.      * Waits to be notified by another thread of a change in this object.
  229.      * <p>
  230.      * This method is similar to the <code>wait</code> method of one 
  231.      * argument, but it allows finer control over the amount of time to 
  232.      * wait for a notification before giving up. 
  233.      * <p>
  234.      * The current thread must own this object's monitor. The thread 
  235.      * releases ownership of this monitor and waits until either of the 
  236.      * following two conditions has occurred: 
  237.      * <ul>
  238.      * <li>Another thread notifies threads waiting on this object's monitor 
  239.      *     to wake up either through a call to the <code>notify</code> method 
  240.      *     or the <code>notifyAll</code> method. 
  241.      * <li>The timeout period, specified by <code>timeout</code> 
  242.      *     milliseconds plus <code>nanos</code> nanoseconds arguments, has 
  243.      *     elapsed. 
  244.      * </ul>
  245.      * <p>
  246.      * The thread then waits until it can re-obtain ownership of the 
  247.      * monitor and resumes execution 
  248.      * <p>
  249.      * This method should only be called by a thread that is the owner 
  250.      * of this object's monitor. See the <code>notify</code> method for a 
  251.      * description of the ways in which a thread can become the owner of 
  252.      * a monitor. 
  253.      *
  254.      * @param      timeout   the maximum time to wait in milliseconds.
  255.      * @param      nano      additional time, in nanoseconds range
  256.      *                       0-999999.
  257.      * @exception  IllegalArgumentException      if the value of timeout is
  258.      *                negative or the value of nanos is
  259.      *                not in the range 0-999999.
  260.      * @exception  IllegalMonitorStateException  if the current thread is not
  261.      *               the owner of this object's monitor.
  262.      * @exception  InterruptedException          if another thread has
  263.      *               interrupted this thread.
  264.      * @since      JDK1.0
  265.      */
  266.     public final void wait(long timeout, int nanos) throws InterruptedException {
  267.         if (timeout < 0) {
  268.             throw new IllegalArgumentException("timeout value is negative");
  269.         }
  270.  
  271.         if (nanos < 0 || nanos > 999999) {
  272.             throw new IllegalArgumentException(
  273.                 "nanosecond timeout value out of range");
  274.         }
  275.  
  276.     if (nanos >= 500000 || (nanos != 0 && timeout == 0)) {
  277.         timeout++;
  278.     }
  279.  
  280.     wait(timeout);
  281.     }
  282.  
  283.     /**
  284.      * Waits to be notified by another thread of a change in this object. 
  285.      * <p>
  286.      * The current thread must own this object's monitor. The thread 
  287.      * releases ownership of this monitor and waits until another thread 
  288.      * notifies threads waiting on this object's monitor to wake up 
  289.      * either through a call to the <code>notify</code> method or the 
  290.      * <code>notifyAll</code> method. The thread then waits until it can 
  291.      * re-obtain ownership of the monitor and resumes execution. 
  292.      * <p>
  293.      * This method should only be called by a thread that is the owner 
  294.      * of this object's monitor. See the <code>notify</code> method for a 
  295.      * description of the ways in which a thread can become the owner of 
  296.      * a monitor. 
  297.      *
  298.      * @exception  IllegalMonitorStateException  if the current thread is not
  299.      *               the owner of the object's monitor.
  300.      * @exception  InterruptedException          if another thread has
  301.      *               interrupted this thread.
  302.      * @see        java.lang.Object#notify()
  303.      * @see        java.lang.Object#notifyAll()
  304.      * @since      JDK1.0
  305.      */
  306.     public final void wait() throws InterruptedException {
  307.     wait(0);
  308.     }
  309.  
  310.     /**
  311.      * Called by the garbage collector on an object when garbage collection
  312.      * determines that there are no more references to the object.
  313.      * A subclass overrides the <code>finalize</code> method to dispose of
  314.      * system resources or to perform other cleanup. 
  315.      * <p>
  316.      * Any exception thrown by the <code>finalize</code> method causes 
  317.      * the finalization of this object to be halted, but is otherwise 
  318.      * ignored. 
  319.      * <p>
  320.      * The <code>finalize</code> method in <code>Object</code> does 
  321.      * nothing. 
  322.      *
  323.      * @exception  java.lang.Throwable  [Need description!]
  324.      * @since      JDK1.0
  325.      */
  326.     protected void finalize() throws Throwable { }
  327. }
  328.